home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998…eptember: Technology Seed / September 98 ADC Seed CD.toast / FireWire 1.1 DR2 SDK / Interfaces / DeviceNotify.h next >
Encoding:
C/C++ Source or Header  |  1998-01-15  |  9.3 KB  |  287 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        DeviceNotify.h
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    xxx put the technology version here xxx
  7.  
  8.      DRI:        Milton Soong
  9.  
  10.      Copyright:    © 1984-1996 by Apple Computer, Inc.
  11.                  All rights reserved.
  12.  
  13.      Warning:    *** APPLE INTERNAL USE ONLY ***
  14.                  This file may contain unreleased API's
  15.  
  16.      BuildInfo:    Built by:            SuperMario Build Daemon
  17.                  With Interfacer:    2.0d11   (PowerPC native)
  18.                  From:                DeviceNotify.i
  19.                      Revision:        10
  20.                      Dated:            3/18/96
  21.                      Last change by:    mcs
  22.                      Last comment:    Add mask to ignore service category while generating an event.
  23.  
  24.      Bugs:        Report bugs to Radar component “System Interfaces”, “Latest”
  25.                  List the version information (from above) in the Problem Description.
  26.  
  27. */
  28. #ifndef __DEVICENOTIFY__
  29. #define __DEVICENOTIFY__
  30.  
  31. #ifndef __TYPES__
  32. #include <Types.h>
  33. #endif
  34. #ifndef __KERNEL__
  35. #include <Kernel.h>
  36. #endif
  37. #ifndef __NAMEREGISTRY__
  38. #include <NameRegistry.h>
  39. #endif
  40.  
  41. #ifdef __cplusplus
  42. extern "C" {
  43. #endif
  44.  
  45. #if PRAGMA_IMPORT_SUPPORTED
  46. #pragma import on
  47. #endif
  48.  
  49. #if PRAGMA_ALIGN_SUPPORTED
  50. #pragma options align=mac68k
  51. #endif
  52.  
  53. /*zzz*/
  54. struct RegEntryRef {
  55.     UInt32                             contents[4];
  56. };
  57. typedef struct RegEntryRef RegEntryRef;
  58.  
  59. typedef KernelID    ObjectID;
  60.  
  61. enum
  62. {
  63.     kInvalidObjectID    = nil
  64. };
  65.  
  66. /*zzz*/
  67. //zzz#if FOR_SYSTEM8_PREEMPTIVE
  68. /*
  69.  §
  70. ##############################################################################
  71.     
  72.     File Name: DeviceNotifyPriv.h
  73.     
  74.     Description:
  75.                             The device notification service is used by Maxwell Kernel band
  76.                     Low level family expert code to inform high level "consumers" about
  77.                 hot plugging/un-plugging of devices.
  78.                 
  79.                 The High level families or code modules running in priviledged mode 
  80.                 can subscribe to the service with the DevNRegisterInterestIn().
  81.                 LL Family notifies its consumers through the DevNNotifyThatThisChanged().
  82.     
  83. ##############################################################################
  84. ############################
  85.  Defines
  86. ############################
  87. */
  88. typedef UInt32 DevNRef;
  89. /*
  90.      a connection Reference Num for a particular subscription
  91.                                         a consumer subscription is identified by a unique
  92.                                          DevNSubRef. In order to cancel a consumer registration,
  93.                                         the DevNSubRef must be specified.
  94.                                     
  95.                                         a  Reference Num for a particular notification
  96.                                         A notification is identified by a unique DevNRef,
  97.                                         since a notification can go through couple of states, and 
  98.                                         it needs to be tracked with a unique identifier.
  99.                                     
  100. */
  101. /*
  102.  §
  103. ########################################################################
  104.     Known & valid Service Category definitions are defined in DFM.h
  105. ########################################################################
  106. */
  107.  
  108. enum {
  109.     kDevNAllServiceCategories    = 0xFFFFFFFF                    /* an option to subscribe to ALL valid service catagories*/
  110. };
  111.  
  112.  
  113. enum {
  114.     kMaxNumServiceCategories    = 20                            /* ••• should be in DFM.h •••*/
  115. };
  116.  
  117. /*
  118.  §
  119. ########################################################################
  120.  Event definition:
  121.     If kDevNSoftRequestMask is set in conjunction with an event value,
  122.     then a soft request is indicated, and the DevN will handle all the
  123.     drudgery associated with two-way transactions, etc.
  124.     (e.g. If (kDevNRemoved and kDevNSoftRequestMask) is received, it's 
  125.     a soft eject request)
  126.     If kDevNSoftRequestMask is NOT set, then it's a hard request
  127.      If the kDevNWarningMask is set, then it's an event warning that 
  128.     a given event is about to happen (and the consumer can't do a thing
  129.     about it). It will be followed later on by a gone hard event.
  130.     the kDevNWarningMask and the kDevNSoftRequestMask can NOT be set at
  131.     the same time.
  132. ########################################################################
  133. */
  134. typedef UInt32 DevNEventType;
  135. /*
  136.  pre-defined event mask
  137.  §
  138.  definition of valid global event
  139.  (10/11/95) Events are now enum instead of masks
  140.  enum for "unsigned" values
  141. */
  142.  
  143. enum {
  144.     kDevNSoftRequestMask        = 0x80000000,                    /* bit indicating soft request*/
  145.     kDevNWarningMask            = 0x40000000,                    /* bit indicating a warning request*/
  146.     kDevNIgnoreSCMask            = 0x20000000,                    /* bit indicating ignore service category*/
  147.     kDevNModifierMasks            = 0xE0000000,                    /* combination of all bits above*/
  148.     kDevNAdded                    = 0,                            /* New device/media/bus available*/
  149.     kDevNRemoved                = 1,                            /* Existing device/media/bus now gone*/
  150.     kDevNWakeup                    = 2,                            /* Plug-in sw state no longer needs synchronization*/
  151.     kDevNSleep                    = 3,                            /* Ask to synchronize SOFTWARE state of plug-in*/
  152.                                                                 /* …used by PowerMgr, DriverReplacer, Soft Dev Eject*/
  153.     kDevNBootComplete            = 4,                            /* used by motherboard expert to inform DFM boot complete*/
  154.     kDevNIOInitComplete            = 5,                            /* I/O system initialize complete*/
  155.     kDevNNumOfPredefinedEvtInUse = 6,
  156.     kDevNHighestEvtInUse        = 5
  157. };
  158.  
  159. /* enum for "signed" values*/
  160.  
  161. enum {
  162.     kDevNSoftEject                = 0x80000001                    /* (kDevNRemoved | kDevNSoftRequestMask)*/
  163. };
  164.  
  165. /*
  166.  §
  167. ########################################################################
  168.     Routine return value definition
  169. ########################################################################
  170. */
  171. typedef UInt32 DevNPermissionResponse;
  172. /* status returned by consumer to DevN*/
  173.  
  174. enum {
  175.     kDevNMErrorCodeBase            = 0,
  176.     kDevNPermissionGranted        = kDevNMErrorCodeBase + 0,        /* consumer consented that instant removal of node is OK */
  177.     kDevNPermissionDelayed        = kDevNMErrorCodeBase + 1,        /* can not grant permission now, will inform producer through .*/
  178.                                                                 /* DevN at a later time (ignored by the DevN if hard request) */
  179.     kDevNPermissionDenied        = kDevNMErrorCodeBase + 2,        /* do Not allow requested event to take place*/
  180.                                                                 /*    (ignored by the DevN if hard request)*/
  181.     kDevNInvalidSC                = kDevNMErrorCodeBase + 3,        /* subscribe with invalid Service Category code*/
  182.     kDevNInvalidEvent            = kDevNMErrorCodeBase + 4,        /* subscribe with invalid event mask (zero)*/
  183.     kDevNInvalidHandler            = kDevNMErrorCodeBase + 5,        /* subscribe with NULL handler address*/
  184.     kDevNNoSuchRef                = kDevNMErrorCodeBase + 6,        /* Specified ID can not be found*/
  185.     kDevNRecordNotFound            = kDevNMErrorCodeBase + 7,        /* while unregistering, can not find record in array*/
  186.     kDevNNotEnoughEvent            = kDevNMErrorCodeBase + 8,        /* not enough masks for DevNMCreateNewEvent call*/
  187.     kDevNDeleteInvalid            = kDevNMErrorCodeBase + 9,        /* attempt to DevNMDeleteNewEvent on invalid event masks*/
  188.     kDevNInvalidEventCount        = kDevNMErrorCodeBase + 10,        /* invalid event count parameter being passed in*/
  189.     kDevNInvalidPermission        = kDevNMErrorCodeBase + 11,        /* bad permission returned from consumer*/
  190.     kDevNTokenNotFound            = kDevNMErrorCodeBase + 12,        /* sub record lookup list token not found*/
  191.     kDevNValidPermissionCount    = kDevNMErrorCodeBase + 13
  192. };
  193.  
  194. /*
  195. ########################################################################
  196.     Error code definition has been moved to DevNPermissionResponse
  197. ########################################################################
  198. ########################################################################
  199.     Subroutine Prototype
  200. ########################################################################
  201.  no more handlers
  202.  #pragma    exportAdd DeviceNotify
  203. ######################                    
  204.  called by consumer
  205. ######################    
  206. */
  207. extern OSStatus DevNRegisterInterestIn(OSType myFamily, ItemCount eventCount, DevNEventType *events, ObjectID adminMessageObj, DevNRef *thisRegistration, void *parm);
  208.  
  209. extern OSStatus DevNUnregisterInterest(DevNRef thisID);
  210.  
  211. extern OSStatus DevNMCreateNewEvent(DevNEventType *result);
  212.  
  213. /*
  214.  call to register family defined events.
  215.  itemCount specifies how many events are desired
  216.     (Only create one event at a time)
  217. */
  218. extern OSStatus DevNMDeleteNewEvent(DevNEventType event);
  219.  
  220. /* de-register the given event*/
  221. extern OSStatus DevNDelayedDownwardNotify(DevNRef notifyRef, DevNRef subscriptionRef, DevNPermissionResponse permission);
  222.  
  223. /*
  224.  must be called after an kDevNPermissionDelayed is returned to the DevN
  225.     for a notification response.
  226. ######################                    
  227.  called by producer
  228. ######################                    
  229. */
  230. extern DevNPermissionResponse DevNNotifyThatThisChanged(OSType whichServiceCategory, DevNEventType whatHappened, RegEntryRef *whichDevice, ObjectID adminMessageObj, DevNRef *notRef, void *parm);
  231.  
  232. extern DevNPermissionResponse DevNNotifyEvents(DevNEventType whatHappened, RegEntryRef *whichDevice, ObjectID adminMessageObj, DevNRef *notRef, void *parm);
  233.  
  234. /*
  235.  #pragma exportSkip DeviceNotify
  236. #####################################
  237.  Notification Message definitions        
  238. #####################################
  239. */
  240. struct DevNMessage {
  241.     UInt32                             AdminMessageType;
  242.     UInt32                             subMessageType;
  243.     OSType                             serviceCategory;
  244.     DevNEventType                     event;
  245.     RegEntryRef *                    device;
  246.     void *                            parm;
  247.     DevNRef                         notRef;
  248.     DevNPermissionResponse             returnPermission;
  249. };
  250. typedef struct DevNMessage DevNMessage;
  251.  
  252. /*
  253. #########################################################
  254.     Device Notification sub-message types.    
  255.     (This is in the "subMessageType" field inside
  256.         The DevNMessage structure)
  257. #########################################################
  258. */
  259.  
  260. enum {
  261.     kDevNNotifyMsg                = 0x01,
  262.     kDevNNotifyCancel            = 0x02,
  263.     kDevNNotifyDelayedReply        = 0x03,
  264.     kNextUnusedMsg                = 0x04
  265. };
  266.  
  267. /*zzz*/
  268. typedef OSStatus (*DeviceNotificationHandler) (DevNMessage *pDevNMessage);
  269. /*zzz*/
  270.  
  271. //zzz#endif
  272.  
  273. #if PRAGMA_ALIGN_SUPPORTED
  274. #pragma options align=reset
  275. #endif
  276.  
  277. #if PRAGMA_IMPORT_SUPPORTED
  278. #pragma import off
  279. #endif
  280.  
  281. #ifdef __cplusplus
  282. }
  283. #endif
  284.  
  285. #endif /* __DEVICENOTIFY__ */
  286.  
  287.